Dire que MCP est un standard d’intégration pour agents IA est une chose ; l’intégrer concrètement dans une application Python en est une autre. La plupart des guides disponibles s’arrêtent à l’ouverture d’un serveur hello-world ou se perdent dans les détails du protocole. Ce guide pratique couvre le parcours complet : installer le SDK Python officiel, exposer un serveur MCP avec plusieurs tools et resources, le connecter à un client (Claude Desktop ou un script Python), et gérer les cas opérationnels (gestion d’erreurs, logs, tests). À la fin, vous aurez un pattern de code transposable à un cas métier réel. Développer un agent IA avec LangGraph et des tools persistants : guide pratique en Python
À retenir en 30 secondes : le SDK Python officiel mcp permet de créer un serveur MCP en 20 lignes, en déclarant des tools et resources via des décorateurs typés. Côté client, le même SDK offre une API asynchrone pour établir une session, découvrir les capacités et invoquer les tools. La transport stdio est idéal en local ; le transport streamable HTTP convient aux serveurs distants exposés à plusieurs clients. Agents IA autonomes : guide complet
Installer le SDK et poser les fondations
Le SDK officiel se récupère via pip install mcp[cli]. L’extra cli installe l’utilitaire mcp qui permet de tester un serveur sans client complet. Vous aurez besoin de Python 3.10 ou supérieur, et d’un environnement virtuel propre : la dépendance pydantic est centrale, et des conflits de version avec d’autres bibliothèques IA (LangChain, LlamaIndex) sont fréquents si l’environnement n’est pas isolé.
La structure projet recommandée distingue trois modules : server.py (le serveur MCP et ses tools), tools/ (un fichier par domaine fonctionnel, avec les fonctions métier pures), et tests/ (tests unitaires des tools indépendamment du protocole). Cette séparation permet de tester la logique métier sans monter le serveur, et de réutiliser les mêmes fonctions dans d’autres contextes (API REST, worker batch).
Déclarer un serveur et ses premiers tools
Le squelette minimal d’un serveur MCP tient en une poignée de lignes. On instancie FastMCP (le wrapper haut niveau du SDK), on décore chaque fonction métier avec @mcp.tool(), et on lance le serveur via mcp.run(). Les types Python natifs (str, int, list, Pydantic BaseModel) sont automatiquement convertis en JSON schema exposé au client. La docstring de chaque fonction devient la description vue par le LLM lors de la sélection de tool — elle est donc critique pour la bonne utilisation du tool par l’agent.
Trois règles pratiques émergent de l’expérience. Premièrement, écrire des docstrings orientées « quand utiliser ce tool » plutôt que « que fait ce tool » : le LLM arbitre entre plusieurs tools et a besoin de signaux de sélection. Deuxièmement, retourner des structures claires et typées (via Pydantic) plutôt que des chaînes libres : la sortie du tool est réinjectée dans le contexte du LLM, un format structuré améliore la fiabilité des étapes suivantes — un pattern qui rejoint celui des structured outputs pour les sorties de LLM. Troisièmement, lever des exceptions explicites avec messages métier plutôt que de retourner des chaînes d’erreur ambiguës : le SDK les convertit automatiquement en réponses MCP conformes.
Exposer des resources en complément des tools
Là où les tools sont des actions (lecture-écriture avec effet observable), les resources sont des contenus consultables par le LLM en lecture seule. On les déclare via @mcp.resource(uri="..."), en précisant un URI avec éventuellement des paramètres (par exemple docs://wiki/{page_id}). Le client MCP peut lister les resources disponibles, filtrer, et injecter leur contenu dans son contexte au moment pertinent. Cette distinction tool/resource est clé pour la perception correcte par le LLM : lire la fiche d’un client via une resource évite au modèle de « penser » que l’opération a un effet métier, ce qu’une invocation de tool suggère.
Connecter un client Python au serveur
Le SDK fournit également une couche client. Un script Python simple ouvre une session via stdio_client ou streamablehttp_client, négocie les capacités, puis découvre les tools et resources exposés. L’invocation d’un tool suit un pattern asynchrone (async with) qui gère proprement le cycle de vie de la session. Dans les frameworks d’agents comme LangGraph ou Pydantic AI, l’intégration est encore plus simple : une fonction utilitaire convertit automatiquement les tools MCP en tools consommables par le framework. Vous obtenez ainsi un agent capable d’orchestrer plusieurs serveurs MCP (un pour GitHub, un pour la base interne, un pour le CRM) sans écrire d’intégration spécifique — c’est précisément la promesse du protocole détaillée dans notre article d’introduction au Model Context Protocol en entreprise.
Gérer authentification, erreurs et observabilité
Pour un serveur HTTP distant, l’authentification est aujourd’hui gérée via headers Bearer sur le transport streamable HTTP. L’identité propagée doit être utilisée pour appliquer un contrôle d’accès au niveau de chaque tool : un tool qui crée un ticket Jira doit vérifier que l’identité appelante a bien le droit sur le projet concerné. Côté erreurs, le SDK encourage la levée d’exceptions typées (ToolError, ValidationError) qui sont automatiquement sérialisées en réponses MCP conformes. Côté logs, intégrer OpenTelemetry sur les span d’invocation des tools permet de corréler les appels côté LLM, côté serveur MCP et côté système aval — un pattern que nous avons détaillé dans notre guide sur l’observabilité des systèmes LLM.
Tester un serveur MCP sans client complet
Le CLI mcp dev lance une interface web locale qui liste les tools et resources du serveur, et permet de les invoquer manuellement. C’est l’équivalent de Postman pour le protocole MCP et c’est un outil quotidien pendant le développement. Pour les tests automatisés, deux approches cohabitent : tester les fonctions métier directement (ignorer le protocole), et tester le serveur de bout en bout via le client Python du SDK. Nos équipes recommandent de couvrir les deux niveaux, le second principalement pour détecter les régressions sur la description des schémas et la gestion des erreurs.
Pour aller plus loin, la documentation officielle du SDK Python MCP expose l’ensemble des options avancées (streaming de résultats, progress reporting, roots multiples).
Mon point de vue d’expert
MCP en Python est aujourd’hui mûr pour la production. Le piège que je rencontre le plus souvent chez les équipes françaises est de confondre « implémenter MCP » avec « déplacer tout son code dans un serveur MCP ». Non : votre logique métier doit rester dans des fonctions pures, testables indépendamment. Le serveur MCP est une couche d’exposition fine, qui enveloppe la logique métier avec des docstrings orientées LLM et une typage strict. Cette discipline garde votre code réutilisable au-delà du contexte agentique, et facilite les tests. Si vous démarrez un projet d’agent IA en 2026 avec Python, bâtissez-le sur MCP dès le prototype — vous ne gagnerez pas de temps à repousser cette décision.
FAQ : MCP en Python
- Quelle version de Python et quelles dépendances pour un serveur MCP ?
- Python 3.10 ou supérieur est requis par le SDK officiel. La dépendance principale est
pydanticv2 ; un environnement virtuel isolé est fortement recommandé pour éviter les conflits de version avec les frameworks IA voisins. L’installation standard se fait viapip install mcp[cli]. - Comment choisir entre transport stdio et transport HTTP ?
- Le transport stdio convient parfaitement aux serveurs locaux consommés par un client sur la même machine (Claude Desktop, Cursor). Le transport streamable HTTP est le bon choix dès que le serveur doit être exposé à plusieurs clients, ou sur un réseau. Vous pouvez démarrer en stdio pour le prototype et passer en HTTP sans changer la logique du serveur — seule la commande de lancement diffère.
- Peut-on exposer un serveur MCP existant à plusieurs LLM différents ?
- Oui, c’est précisément l’intérêt du protocole. Un serveur MCP est agnostique au client : il expose ses tools et resources, et n’importe quel client compatible (Claude, GPT via un bridge, un agent LangGraph) peut les consommer. Vous n’avez rien à changer côté serveur pour supporter un nouveau LLM.
- Comment gérer les secrets (API keys, mots de passe) côté serveur MCP ?
- Les secrets doivent être injectés dans l’environnement du processus serveur (variables d’environnement, Vault, secrets manager cloud), jamais embarqués dans le code ni exposés via le protocole. Le client MCP ne voit jamais les credentials ; il interagit uniquement avec les tools de haut niveau, qui utilisent ces credentials pour contacter les systèmes aval. Cette discipline est essentielle en entreprise.